Skip to content

docs(mcp-servers): rewrite MCP Servers pages for ADP GA#4

Merged
micheleRP merged 7 commits intomainfrom
adp-mcp-servers-rewrite
Apr 29, 2026
Merged

docs(mcp-servers): rewrite MCP Servers pages for ADP GA#4
micheleRP merged 7 commits intomainfrom
adp-mcp-servers-rewrite

Conversation

@micheleRP
Copy link
Copy Markdown
Contributor

@micheleRP micheleRP commented Apr 28, 2026 •
edited
Loading

Summary

Greenfield rewrite of the MCP Servers section for the Agentic Data Plane GA (2026-06-15). Bundles three master-plan workflows: Create MCP server (DOC-2111), #9 Register remote (self-hosted) MCP (DOC-2117), #10 User-delegated OAuth for MCP (DOC-2118). Companion to peer rewrites #2 (AI Gateway) and #3 (Transcripts).

Preview

MCP Servers landing: https://deploy-preview-4--redpanda-agentic-data-plane.netlify.app/redpanda-adp/mcp/

Navigate from the landing page to walk every new and stubbed page (5 must-ship + managed catalog + 5 managed deep-dives). The Cloud Management MCP Server section sits as a peer top-level entry, no longer nested.

What this PR does

  • Deletes legacy MCP content migrated from cloud-docs (the YAML-pipeline-authoring era): mcp/pages/remote/ (13 pages), mcp/pages/overview.adoc, mcp/pages/local.adoc, mcp/examples/mcp-tools/ (42 YAML files + test-mcp-tools.sh). The cloud-docs equivalents were deleted in redpanda-data/cloud-docs#562; this PR applies the same cleanup to adp-docs main, where the migration pre-dated #562.
  • Rewrites mcp/index.adoc as the MCP Servers landing — frames managed + self-managed backends, lists the four ADP-UI top-level areas (LLM Providers, MCP Servers, OAuth Providers, My Connections), points at Cloud Management MCP as a peer.
  • Stubs 4 must-ship how-tos + 1 reference page (create-server.adoc, register-remote.adoc, user-delegated-oauth.adoc, test-tools.adoc, managed-catalog.adoc) with full outlines and // TODO: markers for live walkthroughs. Auth section uses the new RemoteMCPConfig.auth oneof (none / static_key / token_passthrough / service_account_oauth / user_oauth); credential_mode and the CredentialMode enum are gone post-proto-rewrite.
  • Stubs 5 should-ship managed deep-dives (managed/sql.adoc, managed/kafka.adoc, managed/slack.adoc, managed/jira.adoc, managed/openapi.adoc). Shared 7-section structure (what the server does → prereqs → configure → test → auth → use with agents → troubleshooting); live-walkthrough TODOs throughout.
  • managed-catalog.adoc lists all 27 user-facing managed types from apps/aigw/internal/mcp/managed/mcps/*/register_mcp.go, grouped by ManagedMCPCategory (AI / AWS / Communication / Database / Google / Streaming / Utility). Deep-dive links for the 5 with dedicated pages.
  • Updates modules/ROOT/nav.adoc — replaces the legacy Remote/Local subsections with the new flat MCP Servers structure; promotes Redpanda Cloud Management MCP Server to a peer top-level section.
  • Cascade retargets xrefs in modules/agents/, modules/observability/, and modules/ROOT/pages/adp-overview.adoc that pointed at deleted mcp:remote/* paths. Mapping: mcp:remote/overview.adoc → mcp:index.adoc; mcp:remote/quickstart.adoc + create-tool.adoc → mcp:create-server.adoc; mcp:remote/oauth-user-delegated.adoc → mcp:user-delegated-oauth.adoc; mcp:remote/monitor-mcp-servers.adoc → mcp:test-tools.adoc; mcp:remote/{patterns,best-practices,scale,troubleshooting,manage-servers}.adoc and mcp:overview.adoc → mcp:index.adoc (no direct equivalents).

Status

  • Beta (2026-05-15): best-effort. Page outlines are in place; live-walkthrough content fills in subsequent commits.
  • GA (2026-06-15): committed milestone.
  • Plan: Confluence companion.

Open questions / known issues

  • Standalone-ADP wording: every page uses generic "the ADP UI" / "your ADP environment" phrasing with // TODO: markers on every concrete sign-in URL, IAM role, OIDC endpoint, feature flag — to be resolved as the standalone ADP product surface ships.
  • Page aliases for deleted /redpanda-cloud/ai-agents/mcp/remote/* URLs: not added in this PR; external inbound links will 404 until we add page-aliases: entries in Weeks 7–8 (or accept the 404s).
  • ManagedMCPType.docs_url destination: confirm with eng whether the field should point at managed-catalog.adoc#anchor-per-type or at the 5 deep-dive pages where they exist.
  • Self-managed terminology: rule throughout the rewrite is "self-managed MCP server" never bare "self-managed" (collision with Self-Managed Redpanda the product). Flagging for docs-team-standards review.
  • adp-la.adoc partial: present on every new page during the rewrite; remove in Weeks 7–8 per the master-plan GA polish pass.
  • Out-of-scope cleanup: the thin remaining cloud-docs/modules/ai-agents/pages/mcp/{configuration,index,overview,quickstart}.adoc placeholder + nav stub is not touched here. That's a separate workstream.
  • Peer PR partial-include bug: PRs Reapply PR #559: AI Gateway documentation rewrite for ADP GA #2 and Reapply PR #560: Transcripts documentation rewrite for ADP GA #3 use include::ai-agents:partial$adp-la.adoc[] (cloud-docs form) instead of include::ROOT:partial$adp-la.adoc[] (the correct adp-docs intra-component form). Worth flagging on those PRs' reviews so the same pattern doesn't propagate.

Preview pages

Test plan

  • Local build (npm run build && npm run serve) renders the MCP Servers nav with 5 must-ship pages, the catalog, and 5 deep-dive entries; Cloud Management MCP renders as a peer top-level section.
  • Walk every must-ship how-to on adp-production — one server of each auth mode (none, static_key, token_passthrough, service_account_oauth, user_oauth), managed + self-managed.
  • Register at least one real self-managed MCP server via register-remote.adoc; confirm tools/list populates.
  • Complete a user-delegated OAuth consent flow end-to-end via user-delegated-oauth.adoc; confirm My Connections state.
  • Run a tool from the Inspector via test-tools.adoc; capture an error case.
  • Walk each of the 5 should-ship deep-dives on adp-production (Weeks 4–6).
  • Editorial pass via docs-team-standards:review on every new page.
  • Remove adp-la.adoc partial includes at GA (Weeks 7–8).

🤖 Generated with Claude Code

@netlify
Copy link
Copy Markdown

netlify Bot commented Apr 28, 2026 •
edited
Loading

✅ Deploy Preview for redpanda-agentic-data-plane ready!

Name Link
🔨 Latest commit 7f654b6
🔍 Latest deploy log https://app.netlify.com/projects/redpanda-agentic-data-plane/deploys/69f2273c29915300080e2101
😎 Deploy Preview https://deploy-preview-4--redpanda-agentic-data-plane.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@micheleRP micheleRP requested a review from JakeSCahill April 28, 2026 18:02
@micheleRP micheleRP marked this pull request as ready for review April 29, 2026 01:18
@micheleRP micheleRP requested a review from a team as a code owner April 29, 2026 01:18
micheleRP and others added 3 commits April 29, 2026 08:53
@micheleRP
docs(mcp-servers): rewrite MCP Servers pages for ADP GA
b128b48 
Greenfield rewrite of the MCP Servers section for the Agentic Data Plane GA
(2026-06-15). Bundles three master-plan workflows: #3 Create MCP server
(DOC-2111), #9 Register remote/self-hosted MCP (DOC-2117), #10 User-delegated
OAuth for MCP (DOC-2118).

Changes:

* Delete legacy MCP content migrated from cloud-docs (the YAML-pipeline-
  authoring era): mcp/pages/remote/ (13 pages), mcp/pages/overview.adoc,
  mcp/pages/local.adoc, mcp/examples/mcp-tools/ (42 YAML files +
  test-mcp-tools.sh). The cloud-docs equivalents were removed in
  redpanda-data/cloud-docs#562; this is the same cleanup applied to adp-docs
  main, where the migration pre-dated #562.
* Rewrite mcp/pages/index.adoc as the MCP Servers landing — frames managed +
  self-managed backends, lists the four ADP-UI top-level areas, points at
  Cloud Management MCP as a peer.
* Stub the 4 must-ship how-tos (create-server, register-remote,
  user-delegated-oauth, test-tools) + the managed-catalog reference, with
  full outlines and // TODO: markers for live walkthroughs on
  adp-production. Auth section uses the new RemoteMCPConfig auth oneof
  (none / static_key / token_passthrough / service_account_oauth /
  user_oauth); credential_mode and the CredentialMode enum are gone post-
  proto-rewrite.
* Stub the 5 should-ship managed deep-dives (sql, kafka, slack, jira,
  openapi). All follow the shared 7-section structure (what the server does
  -> prereqs -> configure -> test -> auth -> use with agents ->
  troubleshooting). Live-walkthrough TODOs throughout.
* managed-catalog.adoc lists all 27 user-facing managed types from
  apps/aigw/internal/mcp/managed/mcps/*/register_mcp.go, grouped by
  ManagedMCPCategory (AI / AWS / Communication / Database / Google /
  Streaming / Utility), with deep-dive links for the 5 with dedicated pages.
* Update modules/ROOT/nav.adoc — replace the legacy Remote/Local
  subsections with the new flat MCP Servers structure; promote Redpanda
  Cloud Management MCP Server to a peer top-level section.
* Cascade: retarget xrefs in modules/agents/, modules/observability/, and
  modules/ROOT/pages/adp-overview.adoc that pointed at deleted
  mcp:remote/* paths. Targets: mcp:remote/overview.adoc -> mcp:index.adoc;
  mcp:remote/quickstart.adoc + create-tool.adoc -> mcp:create-server.adoc;
  mcp:remote/register-external.adoc -> mcp:register-remote.adoc;
  mcp:remote/oauth-user-delegated.adoc -> mcp:user-delegated-oauth.adoc;
  mcp:remote/monitor-mcp-servers.adoc -> mcp:test-tools.adoc;
  mcp:remote/{patterns,best-practices,scale,troubleshooting}.adoc and
  mcp:overview.adoc -> mcp:index.adoc (no direct equivalents).

Beta target (2026-05-15) is best-effort; firm commitment is GA on
2026-06-15. // TODO: markers throughout will be resolved through live
walkthroughs on adp-production in subsequent commits.

Refs: DOC-2111, DOC-2117, DOC-2118
Plan: https://redpandadata.atlassian.net/wiki/spaces/DOC/pages/1869185054

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

# Conflicts:
#	modules/observability/pages/concepts.adoc
#	modules/observability/pages/transcripts.adoc
@JakeSCahill @claude @micheleRP
Fix local playbook to use local filesystem instead of GitHub main
add4024 
The playbook was pulling from GitHub's main branch instead of the local
working directory, causing the build to show old remote/* pages instead
of the new managed/* structure.

Changed content source from GitHub URL to local directory (.) with HEAD
branch so Antora builds from the current branch with all local changes.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@JakeSCahill @claude @micheleRP
Improve MCP documentation for team standards compliance
6be8a41 
Applied comprehensive improvements to all MCP documentation files based on
docs team standards review:

Style improvements:
- Added glossterm macros for key technical terms (tools, resources, prompts,
  topics, clusters, ACLs) on first mention
- Added explicit link text to all xrefs for better accessibility
- Fixed heading capitalization to sentence case
- Improved introduction paragraphs to lead with value/outcome

Content quality:
- Rewrote introductions to be more outcome-focused
- Standardized xref link text across all files
- Improved consistency in terminology usage

Testing:
- Generated Doc Detective test specifications for create-server.adoc
  (4 tests, 41 steps validated)
- Generated Doc Detective test specifications for test-tools.adoc
  (7 tests, 41 steps validated)
- Both test specs validated successfully

Files modified:
- modules/mcp/pages/index.adoc
- modules/mcp/pages/create-server.adoc
- modules/mcp/pages/register-remote.adoc
- modules/mcp/pages/test-tools.adoc
- modules/mcp/pages/user-delegated-oauth.adoc
- modules/mcp/pages/managed-catalog.adoc

Files added:
- modules/mcp/doc-detective-create-server.json
- modules/mcp/doc-detective-test-tools.json

These changes address all critical issues identified in the documentation
review and prepare the content for GA publication.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@micheleRP micheleRP force-pushed the adp-mcp-servers-rewrite branch from 87df153 to 6be8a41 Compare April 29, 2026 14:54
micheleRP and others added 4 commits April 29, 2026 09:01
@micheleRP
update playbook
079c58c
@micheleRP
update playbook
27d560e
@micheleRP @claude
Defer page-aliases that collide with live cloud-docs pages
ea1b131 
Antora rejected aliases pointing at adp-overview.adoc and
ai-gateway/what-is-ai-gateway.adoc because cloud-docs main still
publishes those pages. Defer both entries with a TODO matching the
existing pattern in modules/ROOT/pages/index.adoc, so the build passes
until cloud-docs removes the duplicates.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@micheleRP @claude
Source adp-docs from local checkout in playbook
7f654b6 
Restore the local-filesystem source (`url: .`, `branches: HEAD`) for
adp-docs so the Netlify deploy preview builds the PR branch instead of
re-fetching `main`. Other sources stay on GitHub.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@micheleRP micheleRP merged commit 63b252a into main Apr 29, 2026
5 checks passed
@micheleRP micheleRP deleted the adp-mcp-servers-rewrite branch April 29, 2026 15:46
@micheleRP micheleRP mentioned this pull request May 6, 2026
Merged
8 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@JakeSCahill JakeSCahill JakeSCahill approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@micheleRP @JakeSCahill